lmiranda
2e65b60725
Major refactoring of projman plugin architecture: Skills Extraction (17 new files): - Extracted reusable knowledge from commands and agents into skills/ - branch-security, dependency-management, git-workflow, input-detection - issue-conventions, lessons-learned, mcp-tools-reference, planning-workflow - progress-tracking, repo-validation, review-checklist, runaway-detection - setup-workflows, sprint-approval, task-sizing, test-standards, wiki-conventions Command Consolidation (17 → 12 commands): - /setup: consolidates initial-setup, project-init, project-sync (--full/--quick/--sync) - /debug: consolidates debug-report, debug-review (report/review modes) - /test: consolidates test-check, test-gen (run/gen modes) - /sprint-status: absorbs sprint-diagram via --diagram flag Architecture Cleanup: - Remove plugin-level mcp-servers/ symlinks (6 plugins) - Remove plugin README.md files (12 files, ~2000 lines) - Update all documentation to reflect new command structure - Fix documentation drift in CONFIGURATION.md, COMMANDS-CHEATSHEET.md Commands are now thin dispatchers (~20-50 lines) that reference skills. Agents reference skills for domain knowledge instead of inline content. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
288 lines
11 KiB
Markdown
288 lines
11 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: 2026-01-30 (v5.5.0)
|
|
|
|
---
|
|
|
|
## 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
|
|
|
|
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 `.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:
|
|
```json
|
|
{
|
|
"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 |
|