Template

Files

lmiranda b53aa7cb23 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

4.5 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-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

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 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

4.5 KiB Raw Blame History