Add path safeguards to prevent structural damage

- Create docs/CANONICAL-PATHS.md as single source of truth - Add mandatory path verification rules to CLAUDE.md - Remove dead reference to CORRECT-ARCHITECTURE.md - Add recovery protocol for path issues 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2025-12-12 00:13:34 -05:00
parent 628180b9d1
commit b53aa7cb23
3 changed files with 193 additions and 2 deletions
--- a/docs/CANONICAL-PATHS.md
+++ b/docs/CANONICAL-PATHS.md
@@ -0,0 +1,139 @@
+# 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-12
+
+---
+
+## Repository Root Structure
+
+```
+support-claude-mktplace/
+├── .claude/                    # Claude Code skills
+├── .claude-plugin/             # Root marketplace manifest (if any)
+├── .claude-plugins/            # Local marketplace definitions
+│   └── projman-marketplace/
+│       └── .claude-plugin/
+│           └── 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)
+├── mcp-servers/                # Shared MCP servers (AT ROOT)
+│   ├── gitea/
+│   ├── wikijs/
+│   └── netbox/
+├── plugins/                    # ALL plugins (INSIDE plugins/)
+│   ├── projman/
+│   ├── projman-pmo/
+│   ├── project-hygiene/
+│   └── cmdb-assistant/
+├── 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` |
+
+### MCP Server Paths
+
+| Context | Pattern | Example |
+|---------|---------|---------|
+| MCP server location | `mcp-servers/{server-name}/` | `mcp-servers/gitea/` |
+| MCP server code | `mcp-servers/{server-name}/mcp_server/` | `mcp-servers/gitea/mcp_server/` |
+| MCP venv | `mcp-servers/{server-name}/.venv/` | `mcp-servers/gitea/.venv/` |
+
+### Relative Path Patterns (CRITICAL)
+
+| From | To | Pattern |
+|------|----|---------|
+| Plugin .mcp.json | 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 `mcp-servers/gitea/`:
+```
+plugins/projman/.mcp.json
+  ↑ go up to plugins/projman/     (../)
+  ↑ go up to plugins/             (../)
+  ↑ go up to root/                (../)
+  → go down to mcp-servers/gitea/ (mcp-servers/gitea/)
+
+Result: ../../mcp-servers/gitea/
+With variable: ${CLAUDE_PLUGIN_ROOT}/../../mcp-servers/gitea/
+```
+
+From `.claude-plugins/projman-marketplace/.claude-plugin/marketplace.json` to `plugins/projman/`:
+```
+.claude-plugins/projman-marketplace/.claude-plugin/marketplace.json
+  ↑ go up to .claude-plugin/              (../)
+  ↑ go up to projman-marketplace/         (../)
+  ↑ go up to .claude-plugins/             (../)
+  ↑ go up to root/                        (../)
+  → 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/` from plugin | Missing one level | `../../mcp-servers/` |
+| `./projman` in marketplace | Wrong depth | `./../../../plugins/projman` |
+| Creating `docs/CORRECT-ARCHITECTURE.md` | This file replaces it | Use `docs/CANONICAL-PATHS.md` |
+
+---
+
+## Change Log
+
+| Date | Change | By |
+|------|--------|-----|
+| 2025-12-12 | Initial creation | Claude Code |